home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / dev / misc / cweb_2_8.lha / amiga / cwebman.tex (.txt) < prev    next >
LaTeX Document  |  1993-01-21  |  68KB  |  1,249 lines
  1. \input cwebmac
  2. \parskip 0pt plus 1pt
  3. \def\RA{\char'31 } % right arrow
  4. \def\hang{\hangindent 4em\ignorespaces}
  5. \font\eightrm=cmr8
  6. \font\ninerm=cmr9
  7. \font\ninett=cmtt9
  8. \font\eighttt=cmtt8
  9. \def\Pascal{Pascal}
  10. \font\quoterm=cmssq8
  11. \font\quoteit=cmssqi8
  12. \def\pb{\.{|...|}}
  13. \def\v{\.{\char'174}} % vertical (|) in typewriter font
  14. \def\lpile{\def\cr{\hfill\endline}\matrix} % I only use \lpile by itself
  15. \abovedisplayskip=.5\abovedisplayskip
  16. \belowdisplayskip=.5\belowdisplayskip
  17. \abovedisplayshortskip=.5\abovedisplayshortskip
  18. \belowdisplayshortskip=.5\belowdisplayshortskip
  19. \advance\pageheight by \baselineskip % the manual just got a bit longer
  20. \advance\fullpageheight by \baselineskip
  21. \setpage
  22. \outer\def\section #1.{\penalty-50\vskip 6pt plus 3pt minus 3pt
  23.   \noindent{\bf #1.}\quad\ignorespaces}
  24. \def\lheader{\mainfont\the\pageno\hfill\sc\runninghead\hfill}
  25. \def\rheader{\hfill\sc\runninghead\hfill\mainfont\the\pageno}
  26. \def\runninghead{{\tentt CWEB} USER MANUAL (VERSION 2.8)}
  27. % This verbatim mode assumes that ! marks are !! in the text being copied.
  28. \def\verbatim{\begingroup
  29.   \def\do##1{\catcode`##1=12 } \dospecials
  30.   \parskip 0pt \parindent 0pt \let\!=!
  31.   \catcode`\ =13 \catcode`\^^M=13
  32.   \tt \catcode`\!=0 \verbatimdefs \verbatimgobble}
  33. {\catcode`\^^M=13{\catcode`\ =13\gdef\verbatimdefs{\def^^M{\ \par}\let =\ }} %
  34.   \gdef\verbatimgobble#1^^M{}}
  35. \null\vfill
  36. \noindent
  37. Copyright \copyright\ 1987, 1990, 1992 Silvio Levy and Donald E. Knuth
  38. \bigskip\noindent
  39. Permission is granted to make and distribute verbatim copies of this
  40. document provided that the copyright notice and this permission notice
  41. are preserved on all copies.
  42. \smallskip\noindent
  43. Permission is granted to copy and distribute modified versions of this
  44. document under the conditions for verbatim copying, provided that the
  45. entire resulting derived work is distributed under the terms of a
  46. permission notice identical to this one.
  47. \pageno=0 \titletrue\eject
  48. \centerline{\titlefont The {\ttitlefont CWEB} System of
  49.     Structured Documentation}
  50. \vskip 15pt plus 3pt minus 3pt
  51. \noindent
  52. This document describes a version of Don Knuth's \.{WEB} system,
  53. adapted to \Cee\ by Silvio Levy.  Knuth's original Pascal programs have been
  54. entirely rewritten in \Cee; many changes were made to take
  55. advantage of features offered by \Cee\ but non-existent in \Pascal.
  56. Readers who are familiar with Knuth's memo ``The \.{WEB} System of Structured
  57. Documentation'' will be able
  58. to skim this material rapidly, because \.{CWEB} is essentially a
  59. simplified subset of \.{WEB}. \.{CWEB} does not need \.{WEB}'s features
  60. for macro definition and string handling, because \Cee\ and its
  61. preprocessor already take care of macros and strings. Similarly, the \.{WEB}
  62. conventions of denoting octal and hexadecimal constants by \.{@'77}
  63. and \.{@"3f} are replaced by \Cee's conventions \.{\v077\v} and
  64. \.{\v0x3f\v}, respectively. All other features of \.{WEB} have been
  65. retained, and a few new features have been added.
  66. \section Introduction.
  67. The philosophy behind \.{WEB} is
  68. that an experienced system programmer, who wants to provide the best
  69. possible documentation of software products, needs two things
  70. simultaneously:  a language like \TeX\ for formatting, and a language like
  71. \Cee\ for programming. Neither type of language can provide the
  72. best documentation by itself. But when both are appropriately combined, we
  73. obtain a system that is much more useful than either language separately.
  74. The structure of a software program may be thought of as a ``web'' that is
  75. made up of many interconnected pieces. To document such a program, we want
  76. to explain each individual part of the web and how it relates to its
  77. neighbors. The typographic tools provided by \TeX\ give us an opportunity
  78. to explain the local structure of each part by making that structure
  79. visible, and the programming tools provided by \Cee\ make it possible
  80. for us to specify the algorithms formally and unambiguously. By combining
  81. the two, we can develop a style of programming that maximizes our ability
  82. to perceive the structure of a complex piece of software, and at the same
  83. time the documented programs can be mechanically translated into a working
  84. software system that matches the documentation.
  85. The \.{WEB} system consists of two programs named \.{WEAVE} and \.{TANGLE}.
  86. More precisely, \.{CWEB} calls them \.{CWEAVE} and \.{CTANGLE}.
  87. When writing a \.{CWEB} program the user keeps the
  88. \Cee\ code and the documentation in the same file, called the \.{WEB}
  89. file and generally named \.{something.w}.  The command
  90. `\.{cweave something}' creates an output file \.{something.tex}, which
  91. can then be fed to \TeX, yielding a ``pretty printed'' version of
  92. \.{something.w} that correctly handles
  93. typographic details like page layout and the use of indentation,
  94. italics, boldface, and mathematical symbols. The typeset output also
  95. includes extensive cross-index
  96. information that is gathered automatically.  Similarly, if you run the
  97. command `\.{ctangle something}' you will get a \Cee\ file \.{something.c},
  98. with can then be compiled to yield executable code.
  99. Besides providing a documentation tool, \.{WEB} enhances the \Cee\
  100. language by providing the
  101. ability to permute pieces of the program text, so that a large system can
  102. be understood entirely in terms of small sections and their local
  103. interrelationships.  The \.{TANGLE} program is so named because it takes a
  104. given web and moves the sections from their web structure into the order
  105. required by \Cee; the advantage of programming in \.{WEB} is that the
  106. algorithms can be expressed in ``untangled'' form, with each section
  107. explained separately.  The \.{WEAVE} program is so named because it takes
  108. a given web and intertwines the \TeX\ and \Cee\ portions contained in
  109. each section, then it knits the whole fabric into a structured document.
  110. (Get it? Wow.)  Perhaps there is some deep connection here with the fact
  111. that the German word for ``weave'' is ``{\it web\/}'', and the
  112. corresponding Latin imperative is ``{\it texe\/}''!
  113. A user of \.{CWEB} should be fairly familiar with the \Cee\
  114. programming language.  A minimal amount of acquaintance with \TeX\ is also
  115. desirable, but in fact it can be acquired as one uses \.{WEB}, since
  116. straight text can be typeset in \TeX\ with virtually no knowledge of
  117. that language.  To someone familiar with both \Cee\ and \TeX\ the amount of
  118. effort necessary to learn the commands of \.{WEB} is small.
  119. \section The language.
  120. Two kinds of material go into \.{WEB} files: \TeX\ text and \Cee\ text.
  121. A programmer writing in \.{WEB} should be thinking both of the
  122. documentation and of the \Cee\ program being created;
  123. i.e., the programmer should be instinctively aware of the different
  124. actions that \.{WEAVE} and \.{TANGLE} will perform on the \.{WEB} file.
  125. \TeX\ text is essentially copied without change by \.{WEAVE}, and it is
  126. entirely deleted by \.{TANGLE}; the \TeX\ text is ``pure
  127. documentation.'' \Cee\ text, on the other hand, is formatted by
  128. \.{WEAVE} and it is shuffled around by \.{TANGLE}, according to rules that
  129. will become clear later. For now the important point to keep in mind is
  130. that there are two kinds of text. Writing \.{WEB} programs is something
  131. like writing \TeX\ documents, but with an additional ``\Cee\ mode''
  132. that is added to \TeX's horizontal mode, vertical mode, and math mode.
  133. A \.{WEB} file is built up from units called {\sl sections\/} that are more
  134. or less self-contained.  Each section has three parts:
  135. \yskip\item{1)} A \TeX\ part, containing explanatory material about what
  136. is going on in the section.
  137. \item{2)} A middle part, containing macro definitions that serve as
  138. abbreviations for \Cee\ constructions that would be less comprehensible
  139. if written out in full each time. They are turned by \.{TANGLE} into
  140. preprocessor macro definitions.
  141. \item{3)} A \Cee\ part, containing a piece of the program that
  142. \.{TANGLE} will produce. This \Cee\ code should ideally be about a
  143. dozen lines long, so that it is easily comprehensible as a unit and so
  144. that its structure is readily perceived.
  145. \yskip\noindent The three parts of each section must appear in this order;
  146. i.e., the \TeX\ commentary must come first, then the middle part, and
  147. finally the \Cee\ code. Any of the parts may be empty.
  148. A section begins with either of the symbols `\.{@\ }' or `\.{@*}', where
  149. `\.{\ }' denotes a blank space. A section ends
  150. at the beginning of the next section (i.e., at the next
  151. `\.{@\ }' or `\.{@*}'), or at the end of the file, whichever comes first.
  152. The \.{WEB} file may also contain material that is not part of any section
  153. at all, namely the text (if any) that occurs before the first section.
  154. Such text is said to be ``in limbo''; it is ignored by \.{TANGLE}
  155. and copied essentially verbatim by \.{WEAVE}, so its function is to
  156. provide any additional formatting instructions that may be desired in the
  157. \TeX\ output. Indeed, it is customary to begin a \.{WEB} file with
  158. \TeX\ code in limbo that loads special fonts, defines special macros,
  159. changes the page sizes, and/or produces a title page.
  160. Sections are numbered consecutively, starting with 1. These numbers appear
  161. at the beginning of each section of the \TeX\ documentation output by
  162. \.{WEAVE}, and they appear
  163. as bracketed comments at the beginning and end of the code generated by that
  164. section in the \Cee\ program output by \.{TANGLE}.
  165. Fortunately, you never mention these numbers yourself when you are writing
  166. in \.{WEB}. You just say `\.{@\ }' or `\.{@*}' at the beginning of each
  167. new section, and the numbers are supplied automatically by \.{WEAVE} and
  168. \.{TANGLE}. As far as you are concerned, a section has a
  169. {\sl name\/} instead of a number; its name is specified by writing
  170. `\.{@<}' followed by \TeX\ text followed by `\.{@>}'. When \.{WEAVE}
  171. outputs a section name, it replaces the `\.{@<}' and `\.{@>}' by
  172. angle brackets and inserts the section number in small type. Thus, when you
  173. read the output of \.{WEAVE} it is easy to locate any section that is
  174. referred to in another section.
  175. For expository purposes, a section name should be a good description of the
  176. contents of that section; i.e., it should stand for the abstraction
  177. represented by the section. Then the section can be ``plugged into'' one or
  178. more other sections in such a way
  179. that unimportant details of its inner workings
  180. are suppressed.  A section name therefore ought to be long enough to convey
  181. the necessary meaning.
  182. Unfortunately, it is laborious to type
  183. such long names over and over again, and it is also difficult to specify a
  184. long name twice in exactly the same way so that \.{WEAVE} and \.{TANGLE}
  185. will be able to match the names to the sections. To ameliorate this difficulty,
  186. \.{WEAVE} and \.{TANGLE} let you abbreviate a section name, so long as
  187. the full name appears somewhere in the \.{WEB} file; you can type simply
  188. `\.{@<$\alpha$...@>}', where $\alpha$ is any string that is a prefix of
  189. exactly one section name appearing in the file. For example, `\.{@<Clear
  190. the arrays@>}' can be abbreviated to `\.{@<Clear...@>}' if no other section
  191. name begins with the five letters `\.{Clear}'.  Elsewhere
  192. you might use the abbreviation `\.{@<Clear t...@>}', and so on.
  193. Section names must otherwise match character for character, except
  194. that consecutive characters of white space (spaces, tab marks, newlines, and/or
  195. form feeds) are treated as equivalent to a single space, and such spaces are
  196. deleted at the beginning and end of the name. Thus, `\.{@< Clear { }the
  197. arrays @>}' will also match the name in the previous example.
  198. Spaces following the ellipsis in abbeviations are ignored as well, but
  199. not those before, so that `\.{@<Clear t ...@>}' would not match
  200. `\.{@<Clear the arrays@>}'.
  201. We have said that a section begins with `\.{@\ }' or `\.{@*}', but we
  202. didn't say how it gets divided up into a \TeX\ part, a middle part,
  203. and a \Cee\ part. The middle part begins with the first appearance of
  204. `\.{@d}' or `\.{@f}' in the section, and the \Cee\ part begins with
  205. the first appearance of `\.{@c}' or `\.{@<section name@>=}'.  In the
  206. latter case you are saying, in effect, that the section name stands
  207. for the \Cee\ text that follows. Alternatively, if the \Cee\ part
  208. begins with `\.{@c}' instead of a section name, the current section is
  209. said to be {\sl unnamed}.
  210. The construct `\.{@<section name@>}' can appear
  211. any number of times in the \Cee\ part of a section:
  212. subsequent appearences indicate that the named section is being
  213. ``used'' rather than ``defined'', that is, that the
  214. \Cee\ code for the named section, presumably defined elsewhere, should be
  215. spliced in at this point in the \Cee\ program.  Indeed,
  216. the main idea of \.{TANGLE} is to make a \Cee\ program out of
  217. individual sections, named and unnamed.  The exact way in which this is done
  218. is the following: First all the macro definitions
  219. indicated by `\.{@d}' are turned into \Cee\ preprocessor macro definitions
  220. and copied at the beginning.
  221. Then the \Cee\ parts of unnamed sections are copied down,
  222. in order; this constitutes the initial
  223. approximation $T_0$ to the text of the program. (There should be at least
  224. one unnamed section, otherwise there will be no program.) Then all section
  225. names that appear in the initial text $T_0$ are replaced by the \Cee\
  226. parts of the corresponding sections, and this substitution process
  227. continues until no section names remain. All comments are removed, because
  228. the \Cee\ program is intended only for the eyes of the \Cee\ compiler.
  229. If the same name has been given to more than one section, the \Cee\ text
  230. for that name is obtained by putting together all of the \Cee\ parts in
  231. the corresponding sections. This feature is useful, for example, in a
  232. section named `Global variables', since one can then
  233. declare global variables in whatever sections those variables are
  234. introduced. When several sections have the same name, \.{WEAVE} assigns the
  235. first section number as the number corresponding to that name, and it
  236. inserts a note at the bottom of that section telling the reader to `See
  237. also sections so-and-so'; this footnote gives the numbers of all the other
  238. sections having the same name as the present one. The \Cee\ text
  239. corresponding to a section is usually formatted by \.{WEAVE} so that the
  240. output has an equivalence sign in place of the equals sign in the \.{WEB}
  241. file; i.e., the output says `$\langle\,$section
  242. name$\,\rangle\equiv\null$\Cee\ text'. However, in the case of the second
  243. and subsequent appearances of a section with the same name, this `$\equiv$'
  244. sign is replaced by `$\mathrel+\equiv$', as an indication that the
  245. following \Cee\ text is being appended to the \Cee\ text of another section.
  246. As \.{TANGLE} enters and leaves sections, it inserts preprocessor
  247. \.{\#line} commands into the \Cee\ output file.  This means that
  248. when the compiler gives you error messages, or when you debug your program,
  249. the messages refer to line numbers in the \.{WEB} file, and not in the
  250. \Cee\ file.  In most cases you can therefore
  251. forget about the \Cee\ file altogether.
  252. The general idea of \.{WEAVE} is to make a \.{.tex} file from the \.{WEB}
  253. file in the following way: The first line of the \.{.tex} file
  254. tells \TeX\ to input a file with macros that
  255. define \.{CWEB}'s documentation conventions. The next lines of the file
  256. will be copied from whatever \TeX\ text is in limbo before the first
  257. section.  Then comes the output for each section in turn, possibly
  258. interspersed with end-of-page marks.  Finally, \.{WEAVE} will generate a
  259. cross-reference index that lists each section number in which each \Cee\
  260. identifier appears, and it will also generate an alphabetized list
  261. of the section names, as well as a table of contents that
  262. shows the page and section numbers for each ``starred'' section.
  263. What is a ``starred'' section, you ask? A section that begins with `\.{@*}'
  264. instead of `\.{@\ }' is slightly special in that it denotes a new major
  265. group of sections. The `\.{@*}' should be followed by the title of this
  266. group, followed by a period. Such sections will always start on a new page
  267. in the \TeX\ output, and the group title will appear as a running headline
  268. on all subsequent pages until the next starred section. The title will also
  269. appear in the table of contents, and in boldface type at the beginning of
  270. its section. Caution:  Do not use \TeX\ control sequences in such titles,
  271. unless you know that the \.{cwebmac} macros will do the right thing with
  272. them. The reason is that these titles are converted to uppercase when
  273. they appear as running heads, and they are converted to boldface when they
  274. appear at the beginning of their sections, and they are also written out to
  275. a table-of-contents file used for temporary storage while \TeX\ is
  276. working; whatever control sequences you use must be meaningful in all
  277. three of these modes.
  278. The \TeX\ output produced by \.{WEAVE} for each section consists of
  279. the following: First comes the section number (e.g., `\.{\\M123.}'
  280. at the beginning of section 123, except that `\.{\\N}' appears in place of
  281. `\.{\\M}' at the beginning of a starred section). Then comes the
  282. \TeX\ part of the section, copied almost verbatim except as noted
  283. below. Then comes the middle part and the \Cee\ part, formatted
  284. so that there will be a little extra space between them if both are
  285. nonempty. The middle and \Cee\ parts are obtained by inserting
  286. a bunch of funny-looking \TeX\ macros into the \Cee\ program; these
  287. macros handle typographic details about fonts and proper math spacing,
  288. as well as line breaks and indentation.
  289. When you are typing \TeX\ text, you will probably want to make frequent
  290. reference to variables and other quantities in your \Cee\ code, and you
  291. will want those variables to have the same typographic treatment
  292. when they appear in your text as when they appear in your
  293. program.  Therefore the \.{WEB} language allows you to get the effect of
  294. \Cee\ editing within \TeX\ text, if you place `\.|' marks before and
  295. after the \Cee\ material. For example, suppose you want to say something
  296. like this:
  297. $$\hbox{ If \\{pa} is declared as `\&{int} ${}{*}\\{pa}$',
  298. the assignment $\\{pa}\K{\AND}\|a[\T{0}]$ makes \\{pa}
  299. point to the zeroth element of \|a.}$$
  300. The \TeX\ text would look like this in your \.{WEB} file:
  301. $$\lpile{\.{If |pa| is declared as `|int *pa|', the}\cr
  302. \.{assignment |pa=\&a[0]| makes |pa| point
  303. to the zeroth element of |a|.}\cr}$$
  304. And \.{WEAVE} translates this into something you are glad you didn't have
  305. to type:
  306. $$\lpile{\.{If \\\\\{pa\} is declared as
  307.   `\\\&\{int\} \$\{\}\{*\}\\\\\{pa\}\$',}\cr
  308. \.{the assignment \$\\\\\{pa\}\\K\{\\AND\}\\|a[\\T\{0\}]\$}\cr
  309. \.{makes \\\\\{pa\} point to the zeroth element of \\|a.}\cr}$$
  310. Incidentally, the cross-reference index that \.{WEAVE} would make, in
  311. the presence of a comment like this, would include
  312. the current section number as one of the index entries for \\{pa},
  313. even though \\{pa} might not appear in the \Cee\ part of
  314. this section. Thus, the index covers references to identifiers in
  315. the explanatory comments as well as in the program itself; you will
  316. soon learn to appreciate this feature. However, the identifiers
  317. \&{int} and \|a\ would not be indexed,
  318. because \.{WEAVE} does not make index entries for reserved words or
  319. single-letter identifiers. Such identifiers are felt to be so ubiquitous
  320. that it would be pointless to mention every place where they occur.
  321. Although a section begins with \TeX\ text and ends with \Cee\ text, we
  322. have noted that the dividing line isn't sharp, since \Cee\ text can be
  323. included in \TeX\ text if it is enclosed in `\pb'.  Conversely, \TeX\ text
  324. also appears frequently within \Cee\ text, because everything in
  325. comments (i.e., between \.{/*} and \.{*/}) is treated as \TeX\ text.
  326. Furthermore, a section name, like a comment, is expected to be found
  327. in \Cee\ text, but the name itself consists of \TeX\ text; thus, a \.{WEB} file
  328. typically involves constructions like `\.{if} \.{(x==0)}
  329. \.{@<Empty} \.{the} \.{|buffer|} \.{array@>}' where we go back and forth
  330. between \Cee\ and \TeX\ conventions in a natural way.
  331. To include a section name in \TeX\ text, that is, in the \TeX\ part of
  332. a section or in a \Cee\ comment, you can enclose it in `\pb'.  In this case
  333. the section name is being ``cited'', rather than defined or used.
  334. \section Macros.
  335. The control code \.{@d} followed by
  336. $$\\{identifier}\.{ }\hbox{\Cee\ text}\qquad\hbox{or by}\qquad
  337. \\{identifier}\.(\\{par}_1,\ldots,\\{par}_n\.{) }\hbox{\Cee\ text}$$
  338. (where there is no blank between the
  339. \\{identifier} and the parentheses in the second case) is
  340. transformed by \.{TANGLE} into a preprocessor command, starting with
  341. \.{\#define}, which is printed at the top of the \Cee\ output file
  342. as explained earlier.
  343. A `\.{@d}' macro definition can go on for several lines, and the
  344. newlines don't have to be protected by backslashes, since \.{TANGLE}
  345. itself inserts the backslashes.   If
  346. for any reason you need a \.{\#define} command at a specific spot in
  347. your \Cee\ file, you can treat it as \Cee\ code, instead of as a
  348. \.{WEB} macro; but then you do have to protect newlines yourself.
  349. \section Strings and constants.
  350. If you want a string to appear in the \Cee\ file, delimited by pairs of
  351. \.' or \." marks as usual, you can type it exactly so in the \.{WEB} file,
  352. except that the character `\.@' should be typed `\.{@@}' (it becomes a
  353. control code, the only one that can appear in strings; see below).
  354. Strings should end on the same line as they begin, unless there's a
  355. backslash at the end of lines within them.
  356. \TeX\ and \Cee\ have different ways to refer to octal and hex constants,
  357. because \TeX\ is oriented to technical writing while \Cee\ is oriented to
  358. computer processing.  In \TeX\ you
  359. make a constant octal or hexadecimal by prepending \.' or \.",
  360. respectively, to it; in \Cee\ the constant should be preceded by \.0
  361. or \.{0x}.  In \.{WEB} it seems reasonable to let each convention hold
  362. in its respective realm; so in \Cee\ text you get $40_8$ by typing
  363. `\.{040}', which \.{TANGLE} faithfully copies into the \Cee\ file (for
  364. the compiler's benefit) and which \.{WEAVE} prints as $\T{\~40}$.
  365. Similarly, \.{WEAVE} prints the hexadecimal \Cee\ constant `\.{0x20}'
  366. as \T{\^20}. The use of italic font for octal digits and typewriter font
  367. for hexadecimal digits makes the meaning of such constants clearer in
  368. a document. For consistency, then, you
  369. should type `\.{|040|}'  or `\.{|0x20|}'
  370. in the \TeX\ part of the section.
  371. \section Control codes.
  372. A \.{WEB} {\sl control code\/}
  373. is a two-character combination of which the first is `\.@'.
  374. We've already seen the meaning of several control codes; here is a
  375. complete list of all of them.
  376. The letters $L$, $T$,
  377. $C$, $\\{Se}$, $\\{Co}$, and/or $S$ following each code indicate whether or not that
  378. code is allowable in limbo, in \TeX\ text, in \Cee\ text, in section
  379. names, in comments, and/or in strings.  A bar over such a letter means
  380. that the control code terminates the present part of the \.{WEB} file; for
  381. example, $\overline L$ means that this control code ends the limbo material
  382. before the first section.
  383. \gdef\@#1[#2] {\penalty-100\yskip\hangindent 2em\noindent\.{@#1\unskip
  384.   \spacefactor1000{ }}$[#2]$\quad}
  385. \def\more{\hangindent 2em \hangafter0}
  386. \def\oP{\overline C}
  387. \def\oT{\overline T\mskip1mu}
  388. \@@ [\\{Co},L,\\{Se},C,S,T] A double \.@ denotes the single character `\.@'. This is
  389. the only control code that is legal in limbo, in comments, and in strings.
  390. Note that you must use this convention if you are giving an internet
  391. email address in a \.{WEB} file (e.g., \.{levy@@math.berkeley.edu}).
  392. \@\ [\overline L,\oP,\oT] This denotes the beginning of a new
  393. (unstarred) section. A tab mark or form feed or end-of-line character
  394. is equivalent to a space when it follows an \.@ sign (and in most
  395. other cases).
  396. \@* [\overline L,\oP,\oT] This denotes the beginning of a new starred
  397. section, i.e., a section that begins a new major group. The title of the new
  398. group should appear after the \.{@*}, followed by a period. As explained
  399. above, \TeX\ control sequences should be avoided in such titles unless
  400. they are quite simple. When \.{WEAVE} and \.{TANGLE} read a \.{@*}, they
  401. print an asterisk on the terminal
  402. followed by the current section number, so that the user
  403. can see some indication of progress. The very first section should be starred.
  404. % This should be outdented, since it applies to more several items.
  405. \penalty-100\yskip\noindent
  406. The middle part of each section consists of any number of
  407. macro definitions (beginning with \.{@d}) and format definitions (beginning
  408. with \.{@f} or \.{@s}), intermixed in any order.
  409. \@d [\oP,\oT] Macro definitions begin with \.{@d} (or \.{@D}), followed by
  410. an identifier and optional parameters and \Cee\ text as explained earlier.
  411. \@f [\oP,\oT] Format definitions begin with \.{@f} (or \.{@F}); they cause
  412. \.{WEAVE} to treat identifiers in a special way when they appear in
  413. \Cee\ text. The general form of a format definition is `\.{@f} \|l
  414. \|r', followed by an optional comment enclosed between
  415. \.{/*} and \.{*/}, where \|l and \|r
  416. are identifiers; \.{WEAVE} will subsequently treat identifier \|l as it
  417. currently treats \|r. This feature allows a \.{WEB} programmer to invent
  418. new reserved words and/or to unreserve some of \Cee's reserved
  419. identifiers. If \|r is the special identifier `\\{TeX}', identifier \|l
  420. will be formatted as a \TeX\ control sequence; for example,
  421. `\.{@f foo TeX}' in the \.{WEB} file will cause identifier \\{foo} to
  422. be output as \.{\\foo} by \.{WEAVE}. The programmer should define
  423. \.{\\foo} to have whatever custom format is desired, assuming \TeX\
  424. math mode. (Each underline
  425. character is converted to \.{x} when making the \TeX\ control sequence;
  426. thus \\{foo\_bar} becomes \.{\\fooxbar}.)
  427. \more \.{WEAVE} knows that identifiers being
  428. defined with a \&{typedef} should become reserved words; thus you
  429. don't need format definitions very often.
  430. \@s [\oP,\oT] Same as \.{@f}, but \.{WEAVE} does not show the format
  431. definition in the output. This is used mostly in \.{@i} files.
  432. \@c [\oP,\oT] The \Cee\ part of an unnamed section begins with \.{@c}
  433. (or \.{@C}). This causes \.{TANGLE} to append the following \Cee\ code
  434. to the initial program text $T_0$ as explained above. The \.{WEAVE}
  435. processor does not cause a `\.{@c}' to appear explicitly in the \TeX\
  436. output, so if you are creating a \.{WEB} file based on a \TeX-printed
  437. \.{WEB} documentation you have to remember to insert \.{@c} in the
  438. appropriate places of the unnamed sections.
  439. \@p [\oP,\oT] The \Cee\ part of an unnamed section may alternatively begin
  440. with \.{@p} (or \.{@P}), for compatibility with other \.{WEB} systems.
  441. \.{CWEB} treats \.{@c} and \.{@p} identically.
  442. \more Because of the rules by which every section is broken into three parts,
  443. the control codes `\.{@d}', `\.{@f}', `\.{@c}', and `\.{@p}'
  444. are not allowed to occur once the \Cee\ part of a section has begun.
  445. \@< [C,\oT] A section name (or unambiguous prefix, as discussed above)
  446. is delimited by \.{@<} and \.{@>}, and consists of \TeX\ text;
  447. but the whole construct \.{@<...@>} is conceptually a \Cee\ element.
  448. (In this sense a section name is like a \Cee\ comment.)
  449. The \TeX\ text should not contain any \.{WEB} control codes
  450. except \.{@@}, unless these control codes appear in \Cee\ text that
  451. is delimited by \pb.  An occurrence of a section name may indicate
  452. that the section is being defined, used, or cited.
  453. \more
  454. A \.{@<} appearing in the \TeX\ part (or the middle part) of a section
  455. inaugurates the \Cee\ part of the section, and defines the following section
  456. name to stand for the subsequent \Cee\ code. The closing \.{@>} should be
  457. followed by \.{=} or \.{+=}.
  458. \more
  459. In the \Cee\ part of a section, \.{@<...@>} indicates that the named
  460. section is being used (its \Cee\ definition is spliced in by
  461. \.{TANGLE}, as explained above).  As an error-detection measure,
  462. \.{TANGLE} and \.{WEAVE} complain if such a section name is followed
  463. by \.=, because most likely this is meant as the definition of a new
  464. section, and so should be preceded by \.{@\ }.  If you really want to
  465. say $\langle\,$foo$\,\rangle=\\{bar}$, where $\langle\,$foo$\,\rangle$
  466. is being used and not defined, put a newline before the \.=.
  467. \more
  468. Finally, \.{|@<...@>|} appearing in a \TeX\ context (in the \TeX\ part
  469. of a section, or in a comment) means that the named section is being
  470. referred to.  Such an occurrence is ignored by \.{TANGLE}. Note that
  471. even here we think of the section name as being a \Cee\ element, hence
  472. the \pb.  There is one \TeX\ context where
  473. \.{|@<...@>|} is not allowed: inside another section name.
  474. \@( [C,\oT] A section name can begin with \.{@(} instead of \.{@<}.
  475. Everything works exactly as before, except that \.{@(foo@>} denotes
  476. a special section name all of whose \Cee\ code is written by \.{TANGLE}
  477. to file \.{foo}. In this way you can get multiple-file output from
  478. a single \.{WEB} file. (The \.{@d} definitions are not output
  479. to such files, only to the master \.{.c} file.)
  480. \@' [C] This control code is dangerous because it has quite different
  481. meanings in \.{CWEB} and the original \.{WEB}. In \.{CWEB} it produces the
  482. decimal constant corresponding to the ASCII code for a string of length~1
  483. (e.g., \.{@'a'} is \.{TANGLE}d into \.{97} and \.{@'\\t'} into
  484. \.9). You might want to use this if you need to work in ASCII on a
  485. non-ASCII machine; but in most cases the \Cee\ conventions of
  486. \.{<ctype.h>} are adequate for character-set-independent programming.
  487. \@\& [C] The \.{@\&} operation causes whatever is on its left to be
  488. adjacent to whatever is on its right, in the \Cee\ output. No spaces or
  489. line breaks will separate these two items.
  490. \penalty-100\yskip \noindent
  491. The next several control codes introduce ``control
  492. texts'', which end with the next `\.{@>}'.  The closing `\.{@>}' must
  493. be on the same line of the \.{WEB} file where the control text began.
  494. Furthermore, no \.{WEB} control codes are allowed in a control text,
  495. not even \.{@@}. (If you need an \.{@} sign you can get around this
  496. restriction by typing `\.{\{\\AT\}}'.)
  497. \@\^ [C,T] The control text that follows, up to the next
  498. `\.{@>}', will be entered into the index together with the identifiers of
  499. the \Cee\ program; this text will appear in roman type. For example, to
  500. put the phrase ``system dependencies'' into the index, type
  501. `\.{@\^system dependencies@>}' in each section
  502. that you want to index as system dependent.
  503. \@. [C,T] The control text that follows will be entered into the index
  504. in \.{typewriter} \.{type}.
  505. \@: [C,T] The control text that follows will be entered into the index
  506. in a format controlled by the \TeX\ macro `\.{\\9}', which you
  507. should define as desired.
  508. \@t [C] The control text that follows will
  509. be put into a \TeX\ \.{\\hbox} and formatted along with the neighboring
  510. \Cee\ program. This text is ignored by \.{TANGLE}, but it can be used
  511. for various purposes within \.{WEAVE}. For example, you can make comments
  512. that mix \Cee\ and classical mathematics, as in `$\\{size}<2^{15}$', by
  513. typing `\.{|size < @t\$2\^\{15\}\$@>|}'.
  514. \@= [C] The control text that follows will
  515. be passed verbatim to the \Cee\ program.
  516. \@q [C,T] The control text that follows will
  517. be totally ignored; it's a comment for readers of the \.{WEB} file only.
  518. \@! [C,T] The section number in an index entry will be underlined if `\.{@!}'
  519. immediately precedes the identifier or control text being indexed. This
  520. convention is used to distinguish the sections where an identifier is
  521. defined, or where it is explained in some special way, from the sections
  522. where it is used. A~reserved word or an identifier of length one will not
  523. be indexed except for underlined entries. An `\.{@!}' is implicitly inserted
  524. by \.{WEAVE} when an identifier is being defined or declared in \Cee\
  525. code; for example, the definition
  526. $$\hbox{\&{int} \\{array}[\\{max\_dim}], \\{count}${}=\\{old\_count};$}$$
  527. makes the names \\{array} and \\{count} get an underlined entry in the
  528. index.  Statement labels, function definitions like
  529. $\\{main}(\\{argc},\39\\{argv})$, and \&{typedef} definitions also
  530. imply underlining. A function definition doesn't define its arguments;
  531. the arguments will, however, be defined
  532. (i.e., their index entries will be underlined), if their types are
  533. declared before the body of the function in the usual way
  534. (e.g., `\.{int}~\\{argc}; \.{char}~${**}\\{argv}$; $\{\,\ldots\,\}$').
  535. \yskip\noindent
  536. The next eight control codes (namely `\.{@,}', `\.{@/}', `\.{@|}', `\.{@\#}',
  537. `\.{@+}', `\.{@;}', `\.{@[}', and `\.{@]}') have no effect on the \Cee\
  538. program output by \.{TANGLE}; they merely help to improve the readability
  539. of the \TeX-formatted \Cee\ that is output by \.{WEAVE}, in unusual
  540. circumstances. \.{WEAVE}'s built-in formatting method is fairly good
  541. when dealing with syntactically correct \Cee\ text, but
  542. it is incapable of handling all possible cases, because it must deal with
  543. fragments of text involving macros and section names; these fragments do
  544. not necessarily obey \Cee's syntax. Although \.{WEB} allows you to
  545. override the automatic formatting, your best strategy is not to worry
  546. about such things until you have seen what \.{WEAVE} produces automatically,
  547. since you will probably need to make only a few corrections when you are
  548. touching up your documentation.
  549. \@, [C] This control code inserts a thin space in \.{WEAVE}'s output; it is
  550. ignored by \.{TANGLE}. Sometimes you need this extra space if you are using
  551. macros in an unusual way, e.g., if two identifiers are adjacent.
  552. \@/ [C] This control code causes a line break to occur within a \Cee\
  553. program formatted by \.{WEAVE}; it is ignored by \.{TANGLE}. Line breaks
  554. are chosen automatically by \TeX\ according to a scheme that works 99\%\
  555. of the time, but sometimes you will prefer to force a line break so that
  556. the program is segmented according to logical rather than visual
  557. criteria.
  558. \@| [C] This control code specifies an optional line break in the midst of
  559. an expression. For example, if you have
  560. a long expression on the right-hand side of an assignment
  561. statement, you can use `\.{@|}' to specify breakpoints more logical than
  562. the ones that \TeX\ might choose on visual grounds.
  563. \@\# [C] This control code forces a line break, like \.{@/} does,
  564. and it also causes a little extra white space to appear between the lines at
  565. this break. You might use it, for example,
  566. between groups of macro definitions that are logically separate but within
  567. the same section. \.{CWEB} automatically inserts this extra space
  568. between functions, between external declarations and functions, and
  569. between declarations and statements within a function.
  570. \@+ [C] This control code cancels a line break that might otherwise be
  571. inserted by \.{WEAVE}, e.g., before the word `\&{else}', if you want to
  572. put a short if--else construction on a single line. It is ignored by
  573. \.{TANGLE}. If you say `\.{\{@+}' at the beginning of a compound statement
  574. that is the body of a function, the first declaration or
  575. statement of the function will appear on the same line as the
  576. left brace, and it will be indented by the same amount as the
  577. second declaration or statement on the next line.
  578. \@; [C] This control code is treated like a semicolon, for formatting
  579. purposes, except that it is invisible. You can use it, for example, after
  580. a section name or macro when the \Cee\ text represented by that section or macro
  581. is a compound statement or ends
  582. with a semicolon. Consider constructions like
  583. $$\lpile{\.{if (condition) macro @;}\cr
  584. \.{else break;}\cr}$$
  585. where \\{macro} is defined to be a compound statement (enclosed in braces).
  586. This is a well-known infelicity of \Cee\ syntax.
  587. \@{[} [C] Place this before a macro argument that isn't otherwise formatted
  588. correctly.
  589. \@] [C] Place this after a macro argument that isn't otherwise formatted
  590. correctly.
  591. \yskip\noindent
  592. The next two entries describe ``meta'' control codes: they govern the
  593. input that \.{WEB} sees.
  594. \@{x @y @z}[\\{change\_file}]
  595. \.{WEAVE} and \.{TANGLE} are designed to work with two input files,
  596. called \\{web\_file} and \\{change\_file}, where \\{change\_file} contains
  597. data that overrides selected portions of \\{web\_file}. The resulting merged
  598. text is actually what has been called the \.{WEB} file elsewhere in this
  599. report.
  600. \more Here's how it works: The change file consists of zero or more ``changes,''
  601. where a change has the form `\.{@x}$\langle$old lines$\rangle$\.{@y}$\langle$%
  602. new lines$\rangle$\.{@z}'. The special control codes \.{@x}, \.{@y}, \.{@z},
  603. which are allowed only in change files, must appear at the beginning of a line;
  604. the remainder of such a line is ignored.
  605. The $\langle$old lines$\rangle$ represent material that exactly matches
  606. consecutive lines of the \\{web\_file}; the $\langle$new lines$\rangle$
  607. represent zero or more lines that are supposed to replace the old. Whenever
  608. the first ``old line'' of a change is found to match a line in the
  609. \\{web\_file}, all the other lines in that change must match too.
  610. \more Between changes, before the first change, and after the last change,
  611. the change file can have any number of lines that do not begin with
  612. `\.{@x}', `\.{@y}', or~`\.{@z}'. Such lines are bypassed and not used for
  613. matching purposes.
  614. \more This dual-input feature is useful when working with a master \.{WEB} file
  615. that has been received from elsewhere (e.g., \.{tangle.w} or
  616. \.{weave.w} or \.{tex.web}), when changes are desirable to customize the
  617. program for your local computer system. You will be able to debug your
  618. system-dependent changes without clobbering the master web file; and once
  619. your changes are working, you will be able to incorporate them readily
  620. into new releases of the master web file that you might receive from time
  621. to time.
  622. \@i [\\{web\_file}]
  623. Furthermore the \\{web\_file} itself can be a combination of
  624. several files.  When either \.{CWEAVE} or \.{CTANGLE} is reading a file and
  625. encounters the control code \.{@i} at the beginning of a line, it
  626. interrupts normal reading and start looking at the file named after the
  627. \.{@i}, much as the \Cee\ preprocessor does when it encounters an \.{\#include}
  628. line.  After the included file has been entirely read, the program
  629. goes back to the next line
  630. of the original file.  The file name following \.{@i} can be
  631. surrounded by \." characters, but such delimiters are
  632. optional. Include files can nest.
  633. \more
  634. Change files can have lines starting with \.{@i}. In this way
  635. you can replace one included file with another.  It is not possible
  636. to replace individual lines of an included file using `\.{@x}', etc.;
  637. conceptually, the
  638. replacement mechanism described above does its work first, and
  639. its output is then checked for \.{@i} lines.
  640. \section Additional features and caveats.
  641. 1. In certain installations of \.{CWEB} that
  642. {\def\\#1#2{`{\tentex\char'#1#2}'}%
  643. have an extended character set, the characters
  644. \\13, \\01, \\31, \\32, \\34, \\35,
  645. \\36, \\37, \\04, \\20, and \\21}
  646. can be typed as abbreviations for `\.{++}', `\.{--}', `\.{->}',
  647. `\.{!=}', `\.{<=}', `\.{>=}', `\.{==}', `\.{\v\v}', `\.{\&\&}',
  648. `\.{<<}', and `\.{>>}',
  649. respectively.
  650. 2. If you have an extended character set, all of the characters listed
  651. in Appendix~C of {\sl The \TeX book\/} can be used in strings. But you should
  652. stick to standard ASCII characters if you want to write programs that will
  653. be useful to all the poor souls out there who don't have extended
  654. character sets.
  655. 3. The \TeX\ file output by \.{WEAVE} is broken into lines having at most
  656. 80 characters each. The algorithm that does this line breaking is unaware
  657. of \TeX's convention about comments following `\.\%' signs on a line. When
  658. \TeX\ text is being copied, the existing line breaks are copied as well,
  659. so there is no problem with `\.\%' signs unless the original \.{WEB} file
  660. contains a line more than eighty characters long or a line with \Cee\
  661. text in \pb\ that expands to more than eighty characters long. Such lines
  662. should not have `\.\%' signs.
  663. 4. \Cee\ text is translated by a ``bottom up'' procedure that
  664. identifies each token as a ``part of speech'' and combines parts of speech
  665. into larger and larger phrases as much as possible according to a special
  666. grammar that is explained in the documentation of \.{WEAVE}. It is easy to
  667. learn the translation scheme for simple constructions like single
  668. identifiers and short expressions, just by looking at a few examples of
  669. what \.{WEAVE} does, but the general mechanism is somewhat complex because
  670. it must handle much more than \Cee\ itself. Furthermore the output
  671. contains embedded codes that cause \TeX\ to indent and break lines as
  672. necessary, depending on the fonts used and the desired page width. For
  673. best results it is wise to avoid enclosing long \Cee\ texts in \pb, since the
  674. indentation and line breaking codes are omitted when the \pb\ text is
  675. translated from \Cee\ to \TeX. Stick to simple expressions or
  676. statements.  If a \Cee\ preprocessor command is enclosed in \pb,
  677. the \.\# that introduces it must be at the beginning of a line,
  678. or \.{WEAVE} won't print it correctly.
  679. 5. Comments are not permitted in \pb\ text. After a `\.|'
  680. signals the change from \TeX\ text to \Cee\ text, the next `\.|' that is
  681. not part of a string or control text or section name ends the \Cee\ text.
  682. 6. A comment must have properly nested occurrences of left and right
  683. braces, otherwise \.{WEAVE} will complain. But it
  684. does try to balance the braces, so that \TeX\ won't foul up too much.
  685. 7. When you're debugging a program and decide to omit some of your
  686. \Cee\ code, do NOT simply ``comment it out.'' Such comments are not
  687. in the spirit of \.{WEB} documentation; they will appear to readers
  688. as if they were explanations of the uncommented-out instructions.
  689. Furthermore, comments of a program must be valid \TeX\ text; hence
  690. \.{WEAVE} will get confused if you enclose \Cee\ statements in
  691. \.{/*...*/} instead of in \.{/*|...|*/}.  If you must comment out
  692. \Cee\ code, you can surround it with preprocessor commands
  693. like \.{\#if 0==1} and \.{\#endif}.
  694. 8. The \.{@f} feature allows you to define one identifier to act like
  695. another, and these format definitions are carried out sequentially.
  696. In general, a given identifier has only one printed format
  697. throughout the entire document, and this format is used even before
  698. the \.{@f} that defines it. The reason is that \.{WEAVE} operates in two
  699. passes; it processes \.{@f}'s and cross-references on the first pass and
  700. it does the output on the second.  (However, identifiers that
  701. implicitly get a boldface format, thanks to a \.{typedef} declaration,
  702. don't obey this rule: they are printed differently before and after
  703. the relevant \.{typedef}.  This is unfortunate, but hard to fix. You can
  704. get around the restriction by using \.{@s}, before or after the \.{typedef}.)
  705. 9. Sometimes it is desirable to insert spacing into \Cee\ code that is
  706. more general than the thin space provided by `\.{@,}'. The \.{@t} feature
  707. can be used for this purpose; e.g., `\.{@t\\hskip 1in@>}' will
  708. leave one inch of blank space. Furthermore, `\.{@t\\4@>}' can be
  709. used to backspace by one unit of indentation, since the control sequence
  710. \.{\\4} is defined in \.{cwebmac} to be such a backspace. (This
  711. control sequence is used, for example, at the beginning of lines that
  712. contain labeled statements, so that the label will stick out a little at
  713. the left.) You can also use `\.{@t\}\\3\{-5@>}' to force a break
  714. in the middle of an expression.
  715. \section Running the programs.
  716. The \UNIX\ command line for \.{CTANGLE} is
  717. $$\.{ctangle [options] web\_file[.w] [change\_file[.ch] [out\_file]]}$$
  718. and the same conventions apply to \.{CWEAVE}. If no change file is
  719. specified, the change file is null. The extensions \.{.w} and \.{.ch}
  720. are appended only if the given file names contain no dot. If the
  721. web file defined in this way cannot be found, the extension \.{.web}
  722. will be tried. For example, `\.{cweave} \.{cob}' will try to read
  723. \.{cob.w}; failing that, it will try \.{cob.web} before giving up.
  724. If no output file name is specified, the name of the \Cee\ file output by
  725. \.{CTANGLE} is obtained by appending the extension \.{.c};
  726. the name of the \TeX\ file output by \.{CWEAVE} gets the extension \.{.tex}.
  727. Programmers who like terseness might choose to set up their
  728.  operating shell so that `\.{wv}' expands to
  729. `\.{cweave -bhp}'; this will suppress most terminal output from \.{CWEAVE}
  730. except for error messages.
  731. Options are introduced either by a \.- sign, to turn an option off,
  732. or by a \.+ sign to turn one on. For example, `\.{-fb}' turns off
  733. options \.f and \.b; `\.{+s}' turns on option \.s. Options can be
  734. specified before the file names, after the file names, or both. The following
  735. options are currently implemented:
  736. \yskip
  737. \def\option#1 {\textindent{\.#1}\hangindent2\parindent}
  738. \option b Print a banner line at the beginning of execution. (On
  739. by default.)
  740. \option f Force line breaks after each \Cee\ statement formatted
  741. by \.{WEAVE}. (On by default; \.{-f} saves paper but looks less \Cee-like
  742. to some people.) (Has no effect on \.{TANGLE}.)
  743. \option h Print a happy message at the conclusion of a successful
  744. run. (On by default.)
  745. \option p Give progress reports as the program runs. (On by default.)
  746. \option s Show statistics about memory usage after the program
  747. runs to completion. (Off by default.) This feature works only if
  748. the programs have been compiled with the \.{-DSTAT} switch. If you
  749. have large \.{WEB} files or sections, you may need to see
  750. how close you come to exceeding the capacity of \.{TANGLE} and/or \.{WEAVE}.
  751. \option x Include indexes and a table of contents in the \TeX\ file
  752. output by \.{WEAVE}. (On by default.) (Has no effect on \.{TANGLE}.)
  753. \option a Treat Amiga-defined identifiers (like \&{UWORD} or 
  754. \&{\_\_aligned}) as keywords. (Off by default.) This causes these
  755. identifiers to be formatted correctly, and is useful when you write
  756. code that uses the Amiga operating system data types. (Has no effect
  757. on \.{TANGLE}.)
  758. \option g Use the German \.{CWEB} macros instead of the English ones.
  759. (Off by default.) (Has no effect on \.{TANGLE}.)
  760. \option i Indent parameters at function declarations. (On by default.)
  761. This causes the formal parameter declarations at function heads to be
  762. indented. If you specify \.{-i} these declarations will be typeset
  763. flush left. (Some people think this is more logical than indenting
  764. them.) (Has no effect on \.{TANGLE}.)
  765. \section Further details about formatting.
  766. You may not like the way \.{WEAVE} handles certain
  767. situations. If you're desperate, you can customize \.{WEAVE}
  768. by changing its grammar.  This means changing the source code,
  769. a task that you might find amusing. A table of grammar rules
  770. appears in the \.{WEAVE} source listing, and you can make a separate
  771. copy of that table by copying the file \.{prod.w} found in the \.{cweb}
  772. sources and saying `\.{cweave}~\.{-x}~\.{prod}'.
  773. If you compile \.{WEAVE} with the \.{-DDEBUG} option on the command
  774. line, you will be able to see exactly
  775. how \.{WEAVE} is parsing your \Cee\ code by preceding
  776. it with the line `\.{@ @c @2}'. (The control code `\.{@2}'
  777. turns on a ``peeping'' mode, and `\.{@0}' turns it off.)
  778. For example, if you run \.{WEAVE} on the file
  779. \medskip
  780. \begingroup
  781. \verbatim
  782. @ @c @2
  783. main (argc,argv)
  784. char **argv;
  785. { for (;argc>0;argc--) printf("%s\n",argv[argc-1]); }
  786. !endgroup
  787. \endgroup
  788. \medskip\noindent
  789. you get the following gibberish on your screen:
  790. \medskip
  791. \begingroup
  792. \verbatim
  793. [...]
  794. 4:*exp ( +exp+ )...
  795. 8:*exp +exp+ int...
  796. 5:*+exp+ int +unorbinop+...
  797. [...]
  798. 45: +fn_decl+*+{+ -stmt- +}-
  799. 40:*+fn_decl+ -stmt-
  800. 37:*+function-
  801. [...]
  802. !endgroup
  803. \endgroup
  804. \medskip
  805. The first line says that grammar rule 4 has just been applied, and \.{WEAVE}
  806. currently has in its memory a sequence of chunks of \TeX\ code (called
  807. ``scraps'') that are respectively
  808. of type \\{exp} (for expression), open-parenthesis,
  809. \\{exp} again, close-parenthesis, and further scraps that haven't yet
  810. been considered by the parser.  (The \.+ and \.- signs stipulate that
  811. \TeX\ should be in or out of math mode at the scrap boundaries. The \.* shows
  812. the parser's current position.)
  813. Then rule 8 is applied, and
  814. the sequence $(\,exp\,)$ becomes an \\{exp} and so on.  In the
  815. end the whole \Cee\ text has become one big scrap of type \\{function}.
  816. Sometimes things don't work as smoothly, and you get a bunch of
  817. lines lumped together.  This means that \.{WEAVE} could not
  818. digest something in your \Cee\ code.  For instance, suppose
  819. `\.{@<Argument definitions@>}' had appeared instead of
  820. `\.{char **argv;}' in the program above. Then \.{WEAVE} would have
  821. been somewhat mystified, since it thinks that section names
  822. are just \\{exp}s.  Thus it would tell \TeX\ to format
  823. `\X2:Argument declarations\X' on the same line as
  824. `$\\{main}(\\{argc},\39\\{argv}{}$)'.
  825. In this case you should help \.{WEAVE} by putting `\.{@/}' after
  826. `\.{main(argc,argv)}'.
  827. \.{CWEAVE} automatically inserts a bit of extra space between declarations
  828. and the first apparent statement of a block. One way to defeat this is
  829. $$\vbox{\halign{#\hfil\cr
  830. \.{int x;@+@t@>@;@/}\cr
  831. \.{@<Other locals@>@;@\#}\cr}}$$
  832. the `\.{@\#}' will put extra space after `$\langle\,$Other locals$\,\rangle$'.
  833. \section Acknowledgments.
  834. The authors wish to thank all who contributed suggestions and criticism to
  835. the development of \.{CWEB}. We are especially grateful to Norman Ramsey,
  836. Joachim Schnitter, Klaus Guntermann, and Nelson Beebe, who contributed
  837. code.  Ramsey also has made
  838. literate programming accessible to users of yet other languages by means of
  839. his \.{SPIDER} system [see {\sl Communications of the ACM\/ \bf32} (1989),
  840. 1051--1055].
  841. \section Appendices.
  842. The basic ideas of \.{WEB} can be understood most easily by looking at
  843. examples of ``real'' programs. Appendix~A shows the \.{CWEB} input that
  844. generated sections 17--18 of the \.{common.w} file, which contains
  845. routines common to \.{CWEAVE} and \.{CTANGLE}.
  846. Appendix~B shows the corresponding \Cee\ code output by \.{CTANGLE}.
  847. Appendix~C shows the
  848. corresponding \TeX\ code output by \.{CWEAVE},
  849. and Appendix~D shows how that output looks when printed out.
  850. Appendix E is the file that sets \TeX\ up to accept
  851. the output of \.{CWEAVE}, and Appendix~F discusses how to use some of those
  852. macros to vary the output formats.
  853. \vfil\eject
  854. \def\runninghead{APPENDIX A --- {\tentt WEB} FILE FORMAT}
  855. \section Appendix A.
  856. The following is an excerpt of the file \.{common.w},
  857. which contains routines shared by \.{CWEAVE} and \.{CTANGLE}.
  858. Note that some of the lines are indented to show the program structure.
  859. The indentation is ignored by \.{WEAVE} and \.{TANGLE}, but users find
  860. that \.{WEB} files are quite readable if they have some such indentation.
  861. The reader should first compare Appendix~A to Appendix~B; then the
  862. same material should be compared to Appendices~C and~D.
  863. \vskip 6pt
  864. \begingroup \def\tt{\eighttt} \baselineskip9pt
  865. \verbatim
  866. @ Procedure |prime_the_change_buffer| sets |change_buffer| in
  867. preparation for the next matching operation. Since blank lines in the change
  868. file are not used for matching, we have
  869. |(change_limit==change_buffer && !!changing)| if and only if
  870. the change file is exhausted. This procedure is called only when
  871. |changing| is 1; hence error messages will be reported correctly.
  872. @<Func...@>=
  873. prime_the_change_buffer()
  874.   change_limit=change_buffer; /* this value is used if the change file ends */
  875.   @<Skip over comment lines in the change file; |return| if end of file@>;
  876.   @<Skip to the next nonblank line; |return| if end of file@>;
  877.   @<Move |buffer| and |limit| to |change_buffer| and |change_limit|@>;
  878. @ While looking for a line that begins with \.{@@x} in the change file, we
  879. allow lines that begin with \.{@@}, as long as they don't begin with \.{@@y},
  880. \.{@@z} or \.{@@i} (which would probably mean that the change file is fouled up).
  881. @<Skip over comment lines in the change file...@>=
  882. while(1) {
  883.   change_line++;
  884.   if (!!input_ln(change_file)) return;
  885.   if (limit<buffer+2) continue;
  886.   if (buffer[0]!!='@@') continue;
  887.   if (isupper(buffer[1])) buffer[1]=tolower(buffer[1]);
  888.   if (buffer[1]=='x') break;
  889.   if (buffer[1]=='y' || buffer[1]=='z' || buffer[1]=='i') {
  890.     loc=buffer+2;
  891.     err_print("!! This should only appear after a @@x");
  892. @.This should only appear...@>
  893. @ Here we are looking at lines following the \.{@@x}.
  894. @<Skip to the next nonblank line...@>=
  895.   change_line++;
  896.   if (!!input_ln(change_file)) {
  897.     err_print("!! Change file ended after @@x");
  898. @.Change file ended...@>
  899.     return;
  900. } while (limit==buffer);
  901. @ @<Move |buffer| and |limit| to |change_buffer| and |change_limit|@>=
  902.   change_limit=change_buffer-buffer+limit;
  903.   strncpy(change_buffer,buffer,limit-buffer+1);
  904. !endgroup
  905. \endgroup
  906. \vfill\eject
  907. \def\runninghead{APPENDIX B  --- TRANSLATION BY {\tentt TANGLE}}
  908. \section Appendix B.
  909. Here's the portion of the \Cee\ code generated by \.{TANGLE} that corresponds
  910. to Appendix~A.  Notice that sections~13, 14 and~15
  911. have been tangled into section~12.
  912. \vskip6pt
  913. \begingroup \def\tt{\eighttt} \baselineskip9pt
  914. \verbatim
  915. /*:9*//*12:*/
  916. #line 240 "common.w"
  917. prime_the_change_buffer()
  918. change_limit= change_buffer;
  919. /*13:*/
  920. #line 253 "common.w"
  921. while(1){
  922. change_line++;
  923. if(!!input_ln(change_file))return;
  924. if(limit<buffer+2)continue;
  925. if(buffer[0]!!='@')continue;
  926. if(isupper(buffer[1]))buffer[1]= tolower(buffer[1]);
  927. if(buffer[1]=='x')break;
  928. if(buffer[1]=='y'||buffer[1]=='z'||buffer[1]=='i'){
  929. loc= buffer+2;
  930. err_print("!! This should only appear after a @x");
  931. /*:13*/
  932. #line 244 "common.w"
  933. /*14:*/
  934. #line 270 "common.w"
  935. change_line++;
  936. if(!!input_ln(change_file)){
  937. err_print("!! Change file ended after @x");
  938. return;
  939. }while(limit==buffer);
  940. /*:14*/
  941. #line 245 "common.w"
  942. /*15:*/
  943. #line 280 "common.w"
  944. change_limit= change_buffer-buffer+limit;
  945. strncpy(change_buffer,buffer,limit-buffer+1);
  946. /*:15*/
  947. #line 246 "common.w"
  948. /*:12*//*16:*/
  949. !endgroup
  950. \endgroup
  951. \vfill\eject
  952. \def\runninghead{APPENDIX C --- TRANSLATION BY {\tentt WEAVE}}
  953. \section Appendix C.
  954. This excerpt from \.{common.tex} corresponds to Appendix A.
  955. \vskip6pt
  956. \begingroup \def\tt{\eighttt} \baselineskip9pt
  957. \verbatim
  958. \M12. Procedure \\{prime\_the\_change\_buffer} sets \\{change\_buffer} in
  959. preparation for the next matching operation. Since blank lines in the change
  960. file are not used for matching, we have
  961. $(\\{change\_limit}\E\\{change\_buffer}\W\R\\{changing})$ if and only if
  962. the change file is exhausted. This procedure is called only when
  963. \\{changing} is 1; hence error messages will be reported correctly.
  964. \Y\B\4\X4:Functions\X${}\mathrel+\E{}$\6
  965. \\{prime\_the\_change\_buffer}(\,)\1\1\2\2\6
  966. ${}\{{}$\1\6
  967. ${}\\{change\_limit}\K\\{change\_buffer}{}$;\C{ this value is used if the
  968. change file ends }\6
  969. \X13:Skip over comment lines in the change file; \&{return} if end of file\X;\6
  970. \X14:Skip to the next nonblank line; \&{return} if end of file\X;\6
  971. \X15:Move \\{buffer} and \\{limit} to \\{change\_buffer} and \\{change\_limit}%
  972. \X;\6
  973. \4${}\}{}$\2\par \fi
  974. \M13. While looking for a line that begins with \.{@x} in the change file, we
  975. allow lines that begin with \.{@}, as long as they don't begin with \.{@y},
  976. \.{@z} or \.{@i} (which would probably mean that the change file is fouled up).
  977. \Y\B\4\X13:Skip over comment lines in the change file; \&{return} if end of
  978. file\X${}\E{}$\6
  979. \&{while} (\T{1})\5
  980. ${}\{{}$\1\6
  981. ${}\\{change\_line}\PP;{}$\6
  982. \&{if} ${}(\R\\{input\_ln}(\\{change\_file})){}$\1\5
  983. \&{return};\2\6
  984. \&{if} ${}(\\{limit}<\\{buffer}+\T{2}){}$\1\5
  985. \&{continue};\2\6
  986. \&{if} ${}(\\{buffer}[\T{0}]\I\.{'@'}){}$\1\5
  987. \&{continue};\2\6
  988. \&{if} (\\{isupper}(\\{buffer}[\T{1}]))\1\5
  989. ${}\\{buffer}[\T{1}]\K\\{tolower}(\\{buffer}[\T{1}]);{}$\2\6
  990. \&{if} ${}(\\{buffer}[\T{1}]\E\.{'x'}){}$\1\5
  991. \&{break};\2\6
  992. \&{if} ${}(\\{buffer}[\T{1}]\E\.{'y'}\V\\{buffer}[\T{1}]\E\.{'z'}\V\\{buffer}[%
  993. \T{1}]\E\.{'i'}){}$\5
  994. ${}\{{}$\1\6
  995. ${}\\{loc}\K\\{buffer}+\T{2};{}$\6
  996. \\{err\_print}(\.{"!!\ This\ should\ only\ }\)\.{appear\ after\ a\ @x"});\6
  997. \4${}\}{}$\2\6
  998. \4${}\}{}$\2\par
  999. \U12.\fi
  1000. \M14. Here we are looking at lines following the \.{@x}.
  1001. \Y\B\4\X14:Skip to the next nonblank line; \&{return} if end of file\X${}\E{}$\6
  1002. \&{do}\6
  1003. ${}\{{}$\1\6
  1004. ${}\\{change\_line}\PP;{}$\6
  1005. \&{if} ${}(\R\\{input\_ln}(\\{change\_file})){}$\5
  1006. ${}\{{}$\1\6
  1007. \\{err\_print}(\.{"!!\ Change\ file\ ended}\)\.{\ after\ @x"});\6
  1008. \&{return};\6
  1009. \4${}\}{}$\2\6
  1010. \4${}\}{}$\2\6
  1011. \&{while} ${}(\\{limit}\E\\{buffer}){}$;\par
  1012. \U12.\fi
  1013. \M15. \B\X15:Move \\{buffer} and \\{limit} to \\{change\_buffer} and \\{change%
  1014. \_limit}\X${}\E{}$\6
  1015. ${}\{{}$\1\6
  1016. ${}\\{change\_limit}\K\\{change\_buffer}-\\{buffer}+\\{limit};{}$\6
  1017. ${}\\{strncpy}(\\{change\_buffer},\39\\{buffer},\39\\{limit}-\\{buffer}+%
  1018. \T{1});{}$\6
  1019. \4${}\}{}$\2\par
  1020. \Us12\ET16.\fi
  1021. !endgroup
  1022. \endgroup
  1023. \vfil\eject
  1024. \def\runninghead{APPENDIX D --- FINAL DOCUMENT}
  1025. \section Appendix D.
  1026. Here's what Appendix~C looks like when typeset. Appendix G contains the
  1027. entire context.
  1028. \M12. Procedure \\{prime\_the\_change\_buffer} sets \\{change\_buffer} in
  1029. preparation
  1030. for the next matching operation. Since blank lines in the change file are
  1031. not used for matching, we have $(\\{change\_limit}\E\\{change\_buffer}\W\R%
  1032. \\{changing})$
  1033. if and only if the change file is exhausted. This procedure is called only
  1034. when \\{changing} is 1; hence error messages will be reported correctly.
  1035. \Y\B\4\X4:Functions\X${}\mathrel+\E{}$\6
  1036. \\{prime\_the\_change\_buffer}(\,)\1\1\2\2\6
  1037. ${}\{{}$\1\6
  1038. ${}\\{change\_limit}\K\\{change\_buffer}{}$;\C{ this value is used if the
  1039. change file ends }\6
  1040. \X13:Skip over comment lines in the change file; \&{return} if end of file\X;\6
  1041. \X14:Skip to the next nonblank line; \&{return} if end of file\X;\6
  1042. \X15:Move \\{buffer} and \\{limit} to \\{change\_buffer} and \\{change\_limit}%
  1043. \X;\6
  1044. \4${}\}{}$\2\par
  1045. \M13. While looking for a line that begins with \.{@x} in the change file,
  1046. we allow lines that begin with \.{@}, as long as they don't begin with
  1047. \.{@y}, \.{@z} or \.{@i} (which would probably indicate that the
  1048. change file is fouled up).
  1049. \Y\B\4\X13:Skip over comment lines in the change file; \&{return} if end of
  1050. file\X${}\E{}$\6
  1051. \&{while} (\T{1})\5
  1052. ${}\{{}$\1\6
  1053. ${}\\{change\_line}\PP;{}$\6
  1054. \&{if} ${}(\R\\{input\_ln}(\\{change\_file})){}$\1\5
  1055. \&{return};\2\6
  1056. \&{if} ${}(\\{limit}<\\{buffer}+\T{2}){}$\1\5
  1057. \&{continue};\2\6
  1058. \&{if} ${}(\\{buffer}[\T{0}]\I\.{'@'}){}$\1\5
  1059. \&{continue};\2\6
  1060. \&{if} (\\{isupper}(\\{buffer}[\T{1}]))\1\5
  1061. ${}\\{buffer}[\T{1}]\K\\{tolower}(\\{buffer}[\T{1}]);{}$\2\6
  1062. \&{if} ${}(\\{buffer}[\T{1}]\E\.{'x'}){}$\1\5
  1063. \&{break};\2\6
  1064. \&{if} ${}(\\{buffer}[\T{1}]\E\.{'y'}\V\\{buffer}[\T{1}]\E\.{'z'}\V\\{buffer}[%
  1065. \T{1}]\E\.{'i'}){}$\5
  1066. ${}\{{}$\1\6
  1067. ${}\\{loc}\K\\{buffer}+\T{2};{}$\6
  1068. \\{err\_print}(\.{"!\ This\ should\ only\ }\)\.{appear\ after\ a\ @x"});\6
  1069. \4${}\}{}$\2\6
  1070. \4${}\}{}$\2\par
  1071. \U12.\fi
  1072. \M14. Here we are looking at lines following the \.{@x}.
  1073. \Y\B\4\X14:Skip to the next nonblank line; \&{return} if end of file\X${}\E{}$\6
  1074. \&{do}\6
  1075. ${}\{{}$\1\6
  1076. ${}\\{change\_line}\PP;{}$\6
  1077. \&{if} ${}(\R\\{input\_ln}(\\{change\_file})){}$\5
  1078. ${}\{{}$\1\6
  1079. \\{err\_print}(\.{"!\ Change\ file\ ended}\)\.{\ after\ @x"});\6
  1080. \&{return};\6
  1081. \4${}\}{}$\2\6
  1082. \4${}\}{}$\2\6
  1083. \&{while} ${}(\\{limit}\E\\{buffer}){}$;\par
  1084. \U12.\fi
  1085. \M15. \B\X15:Move \\{buffer} and \\{limit} to \\{change\_buffer} and \\{change%
  1086. \_limit}\X${}\E{}$\6
  1087. ${}\{{}$\1\6
  1088. ${}\\{change\_limit}\K\\{change\_buffer}-\\{buffer}+\\{limit};{}$\6
  1089. ${}\\{strncpy}(\\{change\_buffer},\39\\{buffer},\39\\{limit}-\\{buffer}+%
  1090. \T{1});{}$\6
  1091. \4${}\}{}$\2\par
  1092. \Us12\ET16.\fi
  1093. \vfil\eject
  1094. \rightskip=0pt % get out of C mode (cf. \B)
  1095. \sfcode`;=1500 \pretolerance 200 \hyphenpenalty 50 \exhyphenpenalty 50
  1096. \def\runninghead{APPENDIX E --- MACROS FOR FORMATTING}
  1097. \section Appendix E: The \.{cwebmac.tex} file.
  1098. This is the file that extends ``plain \TeX'' format in order to support the
  1099. features needed by the output of \.{WEAVE}.
  1100. \vskip6pt
  1101. \begingroup \def\tt{\eighttt} \baselineskip9pt
  1102. \def\printmacs{\input cwebmac}
  1103. \verbatim
  1104. !printmacs
  1105. !endgroup
  1106. \endgroup
  1107. \vfill\eject
  1108. \def\runninghead{APPENDIX F --- NOTES ON FORMATTING}
  1109. \section Appendix F: How to use \.{CWEB} macros.
  1110. The macros in \.{cwebmac} make it possible to produce a variety of formats
  1111. without editing the output of \.{CWEAVE}, and the purpose of this appendix
  1112. is to explain some of the possibilities.
  1113. \def\point#1.{\yskip\indent#1.\quad\ignorespaces}
  1114. \point 1. Four fonts have been declared in addition to the standard fonts of
  1115. \.{PLAIN} format: You can say `\.{\{\\mc UNIX\}}' to get {\mc UNIX} in
  1116. medium-size caps; you can say `\.{\{\\sc STUFF\}}' to get {\sc STUFF}
  1117. in small caps; and you can select the largish fonts \.{\\titlefont}
  1118. and \.{\\ttitlefont} in the title of your document, where \.{\\ttitlefont}
  1119. is a typewriter style of type. There are macros \.{\\UNIX} and \.{\\Cee}
  1120. to refer to \UNIX\ and \Cee\ with medium-size caps.
  1121. \point 2. When you mention an identifier in \TeX\ text, you normally call
  1122. it `\.{|identifier|}'. But you can also say `\.{\\\\\{identifier\}}'. The
  1123. output will look the same in both cases, but the second alternative
  1124. doesn't put \\{identifier} into the index, since
  1125. it bypasses \.{WEAVE}'s translation from \Cee\ mode. In the second
  1126. case you have to put a backslash before each underline character
  1127. in the identifier.
  1128. \point 3. To get typewriter-like type, as when referring to `\.{WEB}', you
  1129. can use the `\.{\\.}' macro (e.g., `\.{\\.\{WEB\}}'). In the argument to
  1130. this macro you should insert an additional backslash before the symbols
  1131. listed as `special string characters' in the index to \.{WEAVE}, i.e.,
  1132. before backslashes and dollar signs and the like.
  1133. A `\.{\\\ }' here will result in the visible space symbol; to get an
  1134. invisible space following a control sequence you can say `\.{\{\ \}}'.
  1135. If the string is long, you can break it up into substrings that
  1136. are separated by `\.{\\)}'; the latter gives a discretionary backslash
  1137. if \TeX\ has to break a line here.
  1138. \point 4. The three control sequences \.{\\pagewidth}, \.{\\pageheight},
  1139. and \.{\\fullpageheight} can be redefined in the limbo section at the
  1140. beginning of your \.{WEB} file, to change the dimensions of each page.
  1141. The default settings
  1142. $$\lpile{\.{\\pagewidth=6.5in}\cr
  1143.   \.{\\pageheight=8.7in}\cr
  1144.   \.{\\fullpageheight=9in}\cr}$$
  1145. were used to prepare the present report; \.{\\fullpageheight} is
  1146. \.{\\pageheight} plus room for the additional heading and page numbers at
  1147. the top of each page. If you change any of these quantities, you should
  1148. call the macro \.{\\setpage} immediately after making the change.
  1149. \point 5. The \.{\\pageshift} macro defines an amount by which right-hand
  1150. pages (i.e., odd-numbered pages) are shifted right with respect to
  1151. left-hand (even-numbered) ones. By adjusting this amount you may be
  1152. able to get two-sided output in which the page numbers line up on
  1153. opposite sides of each sheet.
  1154. \point 6. The \.{\\title} macro will appear at the top of each page
  1155. in small caps; it is the job name unless redefined.
  1156. \point 7. The first page usually is assigned page
  1157. number 1. To start on page 16, with contents
  1158. on page 15, say this: `\.{\\def\\contentspagenumber\{15\}}
  1159. \.{\\pageno=\\contentspagenumber} \.{\\advance\\pageno by 1}'.
  1160. \point 8. The macro \.{\\iftitle} will suppress the header line if it is
  1161. defined by `\.{\\titletrue}'. The normal value is \.{\\titlefalse}
  1162. except for the table of contents; thus, the contents
  1163. page is usually unnumbered.
  1164. Two macros are provided to give flexibility to the table of
  1165. contents: \.{\\topofcontents} is invoked just before the contents
  1166. info is read, and \.{\\botofcontents} is invoked just after.
  1167. Here's a typical definition, taken from the original \.{WEB} manual:
  1168. $$\lpile{\.{\\def\\topofcontents\{\\null\\vfill}\cr
  1169.   \.{ { }\\titlefalse \% include headline on the contents page}\cr
  1170.   \.{ { }\\def\\rheader\{\\mainfont The \{\\tt WEAVE\}{ }processor\\hfil\}}\cr
  1171.   \.{ { }\\centerline\{\\titlefont The \{\\ttitlefont WEAVE\}{ }processor\}}\cr
  1172.   \.{ { }\\vskip 15pt \\centerline\{(Version 2.5)\}{ }\\vfill\}}\cr}$$
  1173. Redefining \.{\\rheader}, which is the headline for right-hand pages,
  1174. suffices in this case to put the desired information at the top of the
  1175. contents page.
  1176. \point 9. Data for the table of contents is written to a file that
  1177. is read after the indexes have been \TeX ed; there's one line of data
  1178. for every starred section. The file \.{common.toc} might look like this:
  1179. $$\lpile{\.{\\Z \{{ }Introduction\}\{1\}\{2\}}\cr
  1180.   \.{\\Z \{{ }The character set\}\{5\}\{3\}}\cr}$$
  1181. and so on. The \.{\\topofcontents} macro could
  1182. redefine \.{\\Z} so that the information appears in any desired format.
  1183. \point 10. Sometimes it is necessary or desirable to divide the output of
  1184. \.{WEAVE} into subfiles that can be processed separately. For example,
  1185. the listing of \TeX\ runs to more than 500 pages, and that is enough to
  1186. exceed the capacity of many printing devices and/or their software.
  1187. When an extremely large job isn't cut into smaller pieces, the entire
  1188. process might be spoiled by a single error of some sort, making it
  1189. necessary to start everything over.
  1190. Here's a safe way to break a woven file into three parts:
  1191. Say the pieces are $\alpha$,
  1192. $\beta$, and $\gamma$, where each piece begins with a starred section.
  1193. All macros should be defined in the opening limbo section of $\alpha$,
  1194. and copies of this \TeX\ code should be placed at the
  1195. beginning of $\beta$ and of $\gamma$. In order to process the parts
  1196. separately, we need to take care of two things: The starting page
  1197. numbers of $\beta$ and $\gamma$ need to be set up properly, and
  1198. the table of contents data from all three runs needs to be
  1199. accumulated.
  1200. The \.{webmac} macros include two control sequences \.{\\contentsfile} and
  1201. \.{\\readcontents} that facilitate the necessary processing.  We include
  1202. `\.{\\def\\contentsfile\{CONT1\}}' in the limbo section of $\alpha$, and
  1203. we include `\.{\\def\\contentsfile\{CONT2\}}' in the limbo section of
  1204. $\beta$; this causes \TeX\ to write the contents data for $\alpha$ and $\beta$
  1205. into \.{CONT1.TEX} and \.{CONT2.TEX}. Now in $\gamma$ we say
  1206. $$\.{\\def\\readcontents\{\\input CONT1 \\input CONT2 \\input CONTENTS\}};$$
  1207. this brings in the data from all three pieces, in the proper order.
  1208. However, we still need to solve the page-numbering problem. One way to
  1209. do it is to include the following in the limbo material for $\beta$:
  1210. $$\lpile{\.{\\message\{Please type the last page number of part 1: \}}\cr
  1211.   \.{\\read -1 to \\temp \\pageno=\\temp \\advance\\pageno by 1}\cr}$$
  1212. Then you simply provide the necessary data when \TeX\ requests
  1213. it; a similar construction is used at the beginning of $\gamma$.
  1214. This method can, of course, be used to divide a woven file into
  1215. any number of pieces.
  1216. \point 11. Sometimes it is nice to include things in the index that are
  1217. typeset in a special way. For example, we might want to have an
  1218. index entry for `\TeX'. \.{WEAVE} provides two simple ways to
  1219. typeset an index entry (unless the entry is an identifier or a reserved word):
  1220. `\.{@\^}' gives roman type, and `\.{@.}' gives typewriter type.
  1221. But if we try to typeset `\TeX' in roman type by saying, e.g.,
  1222. `\.{@\^\\TeX@>}', the backslash character gets in the way,
  1223. and this entry wouldn't appear in the index with the T's.
  1224. The solution is to use the `\.{@:}' feature, declaring a macro that
  1225. simply removes a sort key as follows:
  1226. $$\.{\\def\\9\#1\{\}}$$
  1227. Now you can say, e.g., `\.{@:TeX\}\{\\TeX@>}' in your \.{WEB} file; \.{WEAVE}
  1228. puts it into the index alphabetically, based on the sort key, and
  1229. produces the macro call `\.{\\9\{TeX\}\{\\TeX\}}' which will ensure that
  1230. the sort key isn't printed.
  1231. A similar idea can be used to insert hidden material into section
  1232. names so that they are alphabetized in whatever way you might wish.
  1233. Some people call these tricks ``special refinements''; others call
  1234. them ``kludges''.
  1235. \point 12. The control sequence \.{\\secno} is set to the number of the
  1236. section being typeset.
  1237. \point 13. If you want to list only the sections that have changed,
  1238. together with the index, put the command `\.{\\let\\maybe=\\iffalse}' in
  1239. the limbo section before the first section of your \.{WEB} file. It's
  1240. customary to make this the first change in your change file.
  1241. \point 14. To get output in languages other than English, redefine the
  1242. macros \.{\\A}, \.{\\ET}, \.{\\Q}, \.{\\U},
  1243. \.{\\ch}, \.{\\fin}, and \.{\\con}. \.{CWEAVE} itself need not be changed.
  1244. \point 15. All accents and special text symbols of plain \TeX\ format
  1245. will work in \.{CWEB} documents just as they are described in
  1246. Chapter~9 of {\sl The \TeX book}, with one exception.
  1247. The dot accent (normally \.{\\.}) must be typed \.{\\:} instead.
  1248. \vfill\end
  1249.